✅ 一、确保已经具备的环境

✅ 二、运行调试命令（VS Code）

🎯 推荐方式（图形化）：

1. 打开 main.dart 文件（位于 lib/ 下）

2. 点击右上角的 ▶️（Run）按钮，或按下快捷键：

   1 2	F5 （调试模式运行） Ctrl + F5（直接运行）

🎯 命令行方式：

1
2
3
4
5
6
7
8

# Android 模拟器/真机
flutter run

# 启动 Web 模式（需 flutter config --enable-web）
flutter run -d chrome

# 启动 iOS 模拟器（macOS）
flutter run -d ios

查看所有可用设备：

1

flutter devices

✅ 三、常见调试目标说明

✅ 四、调试 Vue3 HTML Tab 的特殊配置（如果在 Flutter 中用 WebView 加载 Vue3）

如果运行的 Flutter 工程中嵌入了 Vue 页面（WebView），确保以下：

1. WebView 权限（Android）

在 android/app/src/main/AndroidManifest.xml 中添加：

1

<uses-permission android:name="android.permission.INTERNET"/>

2. iOS 权限（可选）

在 ios/Runner/Info.plist 中添加：

1
2
3
4
5

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

✅ 五、调试技巧与建议

✅ 终极调试 checklist（排错利器）

运行以下命令：

1

flutter doctor -v

查看所有环境是否都已就绪。出现 ! 或 ✗ 的部分需要重点修复（比如缺设备、SDK 路径错误、模拟器未运行等）。

✅ Bonus：添加调试配置 launch.json（可选）

在 .vscode/launch.json 中添加：

1
2
3
4
5
6
7
8
9
10

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flutter: Launch app",
      "request": "launch",
      "type": "dart"
    }
  ]
}

这样可以通过 F5 快速调试而无需手动选择设备。

贴出的 flutter doctor 输出显示有几项关键问题和一些可忽略项，我来逐条分析并给清晰的修复建议：

🔴 ❶ Android SDK 缺失 android-36 平台

1

X Android SDK file not found: D:\android_sdk\platforms\android-36\android.jar

💡 问题原因：

当前的 Flutter 项目或 IDE 使用了 Android 36（API 36），但这个 SDK 没有安装或不完整。

✅ 解决方法：

方法 A：安装 Android 36（推荐）

打开 Android Studio → SDK Manager：

1. 点击菜单栏：Tools → SDK Manager
2. 切换到 SDK Platforms 选项卡
3. 勾选 Android 14 (API Level 34) 或 Android 15 Preview / 36
4. 点击 Apply → 安装

如果找不到 API 36，可以用命令行安装：

1

sdkmanager "platforms;android-36"

⚠️ 如果 Android 36 是预览版不稳定，建议改用 Android 33 或 34。

方法 B：修改 compileSdkVersion 降级到 33 或 34

如果不想用 Android 36，可以手动更改 Flutter 项目的构建版本：

1. 打开 android/app/build.gradle
2. 找到以下配置：

1

compileSdkVersion 36

改成：

1

compileSdkVersion 33

3. 同时确认 targetSdkVersion 与 minSdkVersion 合理设置，例如：

1
2
3
4

defaultConfig {
    minSdkVersion 21
    targetSdkVersion 33
}

4. 保存后重新运行：

1
2
3

flutter clean
flutter pub get
flutter run

🟠 ❷ 网络资源错误：信号灯超时

1
2

X A network error occurred while checking "https://pub.dev/"
X A network error occurred while checking "https://maven.google.com/"

💡 问题原因：

Flutter 连接不上 pub.dev 和 maven.google.com，常见于：

• 国内网络被墙
• 无代理 / VPN
• 公司网络限制

✅ 解决方法：

方法 A：配置国内镜像

1. Flutter 包镜像设置：

创建或修改文件：

1

C:\Users\<的用户名>\.flutter_settings

添加内容：

1
2

PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

2. 临时设置（命令行）

1
2
3

set PUB_HOSTED_URL=https://pub.flutter-io.cn
set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
flutter pub get

3. Maven 镜像设置（for Android）

修改 android/build.gradle：

1
2
3
4
5
6
7
8

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/jcenter' }
        mavenCentral()
        google()
    }
}

🟡 ❸ Visual Studio 缺失（可忽略，除非开发 Windows 桌面 app）

1

X Visual Studio not installed; this is necessary to develop Windows apps.

✅ 如果只做 Android / Web 开发：可忽略此项

✅ 如果想开发 Windows 桌面应用：

1. 下载 Visual Studio：
   https://visualstudio.microsoft.com/downloads/

2. 勾选 Desktop development with C++
   安装后重新运行 flutter doctor

🟢 其余都是正常状态：

• ✅ Android Studio 正常
• ✅ VS Code 正常
• ✅ 有 3 个连接设备（模拟器或真机）
• ✅ Flutter SDK 可用

✅ 最终操作建议顺序

1
2
3
4
5
6
7
8
9
10

# 1. 降低或安装 Android SDK 36
flutter clean

# 2. 修改 compileSdkVersion 或安装 SDK

# 3. 配置 pub 和 maven 镜像
flutter pub get

# 4. 启动项目
flutter run

这段 build.gradle.kts（Kotlin DSL） 是 Flutter Android 项目中的配置文件，用于设置 Android 原生层的构建参数，配合 Flutter 插件运行。这表示创建的是一个 Flutter 与 Kotlin 混合项目。

✅ 配置解读说明（适用于 Flutter 多平台开发）

🔧 plugins 部分

1
2
3
4
5

plugins {
    id("com.android.application")         // 应用程序构建支持
    id("kotlin-android")                  // 支持 Kotlin for Android
    id("dev.flutter.flutter-gradle-plugin") // Flutter Gradle 插件
}

• 顺序很重要：Flutter 插件必须在 com.android.application 和 kotlin-android 后加载。
• 使用 Kotlin DSL 而不是 Groovy 是 Android Studio 最新推荐方式。

⚙️ android 配置详解

1
2
3
4

android {
    namespace = "com.example.zhangxiaozhi"
    compileSdk = flutter.compileSdkVersion
    ndkVersion = flutter.ndkVersion

• namespace：Android 包名，实际用于 AndroidManifest。
• compileSdk、ndkVersion：从 Flutter 定义中读取，通常无需手动设置。

📱 defaultConfig

1
2
3
4
5
6
7

defaultConfig {
    applicationId = "com.example.zhangxiaozhi"
    minSdk = flutter.minSdkVersion
    targetSdk = flutter.targetSdkVersion
    versionCode = flutter.versionCode
    versionName = flutter.versionName
}

• 这些值是 Flutter 工具链自动注入的，保持一致性。
• 可以修改 applicationId 来设定最终 Android 应用的唯一标识。

🔐 buildTypes

1
2
3
4
5

buildTypes {
    release {
        signingConfig = signingConfigs.getByName("debug")
    }
}

• 这里 release 使用了 debug 签名，是 Flutter 默认的调试构建方式。如果要上传到 Google Play，需自定义 release 签名。

🧩 flutter 块

1
2
3

flutter {
    source = "../.."
}

• 表明 Flutter 源代码主目录在哪里，通常在 Android 子项目之外。

🚀 如何调试运行这个 Flutter 工程？

1. 使用 VS Code 调试步骤：

1. 打开 flutter 项目根目录（不是 android 子目录）。
2. 确保 flutter doctor 通过（特别是 SDK、AVD）。
3. 连接真机或启动虚拟设备。
4. 打开 VS Code → 左侧 ▶️图标 → Run → “Flutter: Launch Android emulator”。
5. F5 或运行 Flutter: Run 命令。

2. Android Studio 调试：

1. 打开整个 Flutter 工程。
2. 顶部下拉选择运行目标设备。
3. 点击 Run 图标。

🧱 如何开发 App Shell + 动态加载 Vue3 HTML？

如果想在 Flutter 中加载 HTML5/Vue3 页面作为“Tab 内容”，可以通过以下方式：

✅ 步骤一：构建 Flutter 壳（App Shell）

用 Flutter 的 Scaffold + BottomNavigationBar 创建基本壳：

1
2
3
4
5
6
7
8

Scaffold(
  body: _tabs[_selectedIndex],
  bottomNavigationBar: BottomNavigationBar(
    currentIndex: _selectedIndex,
    items: [...],
    onTap: (index) => setState(() => _selectedIndex = index),
  ),
)

✅ 步骤二：加载 Vue 页面（通过 WebView）

使用 webview_flutter 插件，加载本地或远程 Vue3 页面：

1
2
3
4

WebView(
  initialUrl: 'http://localhost:8080/index.html',
  javascriptMode: JavascriptMode.unrestricted,
)

• 可以将 Vue3 应用打包成静态文件，部署到本地服务器或嵌入到 Flutter 中（如 assets/web 下）。
• 使用 flutter_inappwebview 可获得更强的功能控制（如 JS 通信）。

✅ 步骤三：支持动态 Tab（Tab 可增删）

可以用 List<Widget> 来管理动态 tabs：

1

List<Widget> _tabs = [TabA(), TabB(), WebViewTab(url: '...')];

• 可以通过配置文件或远程 JSON 动态创建 tab 内容和加载的 Vue 页面。
• 可以实现如下结构：

1
2
3
4

[
  {"title": "首页", "type": "native", "component": "HomePage"},
  {"title": "动态页", "type": "web", "url": "https://xxx/vue.html"}
]

在 Flutter 中解析这个配置，动态构建 tab 列表和内容组件。

🧠 总结